.\" runargs.8
.\" wcm, 2009.12.11 - 2009.12.15
.\" ===
.TH runargs 8 "January 2013" "runtools-2.07" "runtools"
.SH NAME
runargs \- run a program with arguments read from an argument file
.SH SYNOPSIS
.B runargs [\-hV] [\-i]
.I argfile program
.B [
.I args ...
.B ]
.SH DESCRIPTION
.B runargs
runs
.I program
with arguments read from 
.IR argfile .
.PP
An
.I argfile
is a plain text file with zero or more lines.
Each line read is setup as an individual argument to
.I program
in the same order as it is read.
Any leading and/or trailing whitespace is trimmed.
Empty lines and lines beginning with the `#' character are ignored.
.PP
If
.I argfile
is given as a
.RB ` - '
character,
arguments will be taken from stdin.
.PP
Normally any arguments specified in
.I args
are setup to precede the arguments taken from
.IR argfile .
The
.B \-i
option may be used to invert this order.
.PP
If
.I program
does not contain a ``/'' slash character,
.B runargs
will perform a shell-like search for the executable using the
.B PATH
variable in the current environment.
.SH OPTIONS
.TP
.B \-h
Help.
Print a brief usage message to stderr and exit.
.TP
.B \-i
Insert.
Normally
.B runargs
sets up
.I program
with any arguments given in
.I args
before those given in
.IR argfile .
The
.B \-i
option may be used to invert this order,
and insert the arguments taken from 
.I argfile
before any specified in
.IR args .
.TP
.B \-V
Version.
Print the version number to stderr and exit.
.SH EXIT STATUS
.B runargs
exits with one of the following values:
.TP
0
.I program
was invoked and completed successfully.
In this case,
the exit code is returned by the
.IR program ,
rather than by
.B runargs
itself.
.TP
100
.B runargs
failed because of a usage error,
such as an invalid command\-line option or argument.
In this case,
.B runargs
prints a brief error message and usage help to stderr on exit.
.TP
111
.B runargs
failed due to some system or resource error.
In this case,
.B runargs
prints a brief diagnostic message to stderr on exit.
.TP
1\-127
.I program
was invoked and failed with its own non-zero exit status.
.SH CAVEATS
In most cases,
the arguments specified in
.I argfile
will not normally want to follow the shell\-protecting quoting conventions
as might otherwise be used
when running
.I program
in a shell environment.
.SH AUTHOR
Wayne Marshall, http://b0llix.net/perp/
.SH SEE ALSO
.nh
.BR runtools_intro (8),
.BR runargv0 (8),
.BR runchoom (8),
.BR rundetach (8),
.BR rundeux (8),
.BR runenv (8),
.BR runfile (8),
.BR runlimit (8),
.BR runlock (8),
.BR runpause (8),
.BR runsession (8),
.BR runtool (8),
.BR runtrap (8),
.BR runuid (8)
.\" EOF
